From eba25a4fb566a3d27f4346d7d603b0c10dc2fc6f Mon Sep 17 00:00:00 2001
From: H3ALY <ross@healy.xyz>
Date: Wed, 29 Oct 2025 09:47:51 +0000
Subject: [PATCH] comment model.

---
 internal/models/ticket.go | 47 +++++++++++++++++++++++++++------------
 1 file changed, 33 insertions(+), 14 deletions(-)

diff --git a/internal/models/ticket.go b/internal/models/ticket.go
index 6965e1d..9ee3241 100644
--- a/internal/models/ticket.go
+++ b/internal/models/ticket.go
@@ -1,31 +1,50 @@
+// Package models
+// Path: internal/models/
+// File: ticket.go
+//
+// Purpose
+//   Canonical persistence model for tickets as stored in DB,
+//   plus display helpers populated at read time.
+//
+// Responsibilities
+//   - Represents input values for ticket creation
+//   - Stores normalized draw fields for comparison
+//   - Optional fields (bonus, syndicate) use pointer types
+//
+// Notes
+//   - Read-only display fields must not be persisted directly
+//   - TODO: enforce UserID presence once per-user tickets are fully enabled
+
 package models
 
 import "time"
 
 type Ticket struct {
-	Id             int
-	UserId         int
-	SyndicateId    *int
-	GameType       string
-	DrawDate       time.Time
-	Ball1          int
-	Ball2          int
-	Ball3          int
-	Ball4          int
-	Ball5          int
-	Ball6          int
+	Id          int       // Persistent DB primary key
+	UserId      int       // FK to users(id) when multi-user enabled
+	SyndicateId *int      // Optional FK if purchased via syndicate
+	GameType    string    // Lottery type (e.g., Lotto)
+	DrawDate    time.Time // Stored as UTC datetime to avoid timezone issues
+	Ball1       int
+	Ball2       int
+	Ball3       int
+	Ball4       int
+	Ball5       int
+	Ball6       int // Only if game type requires
+
+	// Optional bonus balls
 	Bonus1         *int
 	Bonus2         *int
 	PurchaseMethod string
-	PurchaseDate   string
+	PurchaseDate   string // TODO: convert to time.Time
 	ImagePath      string
-	Duplicate      bool
+	Duplicate      bool // Calculated during insert
 	MatchedMain    int
 	MatchedBonus   int
 	PrizeTier      string
 	IsWinner       bool
 
-	// Used only for display these are not stored in the DB, they mirror MatchTicket structure but are populated on read.
+	// Non-DB display helpers populated in read model
 	Balls       []int
 	BonusBalls  []int
 	MatchedDraw DrawResult