docs: define calendar-aware analytics model

CONTEXT.md

@@ -0,0 +1,54 @@
+# Domain Glossary
+
+## Merchant
+
+A business represented in the source data. A merchant owns terminals, payment sessions, and merchant users. In the MVP, detailed data is visible only within that merchant's authenticated boundary.
+
+## Merchant User
+
+A person/account permitted to authenticate as one merchant. The hackathon seed creates an initial demo user for each merchant; a merchant and a merchant user are not the same concept.
+
+## Terminal
+
+A merchant-owned payment endpoint identified by the source terminal key.
+
+## Payment Session
+
+One payment journey identified by the source session key. A session belongs to one merchant and terminal and can contain one or more payment attempts.
+
+## Payment Attempt
+
+One try within a payment session, distinguished by its try sequence. This is the grain of a source CSV row and must not be confused with a unique payment session.
+
+## Opaque Payer Token
+
+The nullable `payer_card_key` source value. It is an unverified, merchant-scoped token used only for internal approximate repeat-payer analytics. It is not a card number or verified person identifier.
+
+## Import Run
+
+One traceable attempt to ingest a specific source archive/schema using a specific importer revision. It records outcome, counts, validation evidence, and provenance.
+
+## Calendar Date
+
+One civil date enriched with Gregorian and Jalali calendar attributes, Persian month/season, weekday, and reporting attributes.
+
+## Calendar Event
+
+A curated, versioned named period relevant to analysis, such as Nowruz or another Iranian holiday. Event membership is evidence supplied by the calendar model, not inferred by an LLM.
+
+## Reporting Period
+
+An approved time window used for metrics: day, Jalali month, Persian season, calendar event, or another explicitly defined comparison window.
+
+## Analytical Metric
+
+A deterministic numerical measure with a definition, source fields, filters, period, unit, missing-data behavior, and drill-down path.
+
+## Analytics Projection
+
+A rebuildable summary derived from normalized source-of-truth records to answer an approved metric efficiently. A projection is not independent business truth.
+
+## Peer Cohort
+
+An approved group of other merchants used for anonymized comparison. The active merchant is excluded, and a benchmark is suppressed unless at least 10 peers and 1,000 peer sessions contribute.
+