docs: comprehensive v9c architecture plan - Subscription & Coupon System

Added detailed documentation for v9c features:
- Complete database schema (8 new tables)
- Backend architecture (6 new routers, middleware, cron jobs)
- Frontend extensions (pages, components, admin panels)
- Zugriffs-Hierarchie und Stacking-Logik
- Tier-System mit Admin-editierbaren Limits
- Coupon-System (Single-Use + Multi-Use Period)
- User Activity Tracking
- E-Mail Templates
- Migration roadmap (25 steps in 5 phases)

Spätere Features dokumentiert (v9d/v9e):
- Bonus-System & Gamification
- Stripe-Integration
- Partner-Verwaltung
- Admin-Benachrichtigungen

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -96,19 +96,321 @@ mitai-jinkendo/
 - ✅ Automatische SQLite→PostgreSQL Migration bei Container-Start
 - ✅ **Modulare Backend-Architektur**: 14 Router-Module, main.py von 1878→75 Zeilen (-96%)
 
-### Was in v9c kommt:
+### Was in v9c kommt: Subscription & Coupon Management System
-- 🔲 Selbst-Registrierung mit E-Mail-Bestätigung
+**Core Features:**
-- 🔲 Freemium Tier-System (free/basic/premium/selfhosted)
+- 🔲 Selbst-Registrierung mit E-Mail-Verifizierung (Pflicht)
-- 🔲 14-Tage Trial automatisch
+- 🔲 Flexibles Tier-System (free/basic/premium/selfhosted) - Admin-editierbar
-- 🔲 Einladungslinks für Beta-Nutzer
+- 🔲 Trial-System (Dauer konfigurierbar, auto-start nach E-Mail-Verifikation)
-- 🔲 Admin kann Tiers manuell setzen
+- 🔲 **Coupon-System** (2 Typen):
+  - Single-Use Coupons (Geschenke, zeitlich begrenzt)
+  - Multi-Use Period Coupons (z.B. Wellpass, monatlich erneuerbar)
+- 🔲 Coupon-Stacking-Logik (Pause + Resume bei Wellpass-Override)
+- 🔲 Access-Grant-System (zeitlich begrenzte Zugriffe mit Quelle-Tracking)
+- 🔲 User-Activity-Log (Login, Password-Änderungen, Coupon-Einlösungen, etc.)
+- 🔲 User-Stats (Login-Streaks, Nutzungsstatistiken)
+- 🔲 Individuelle User-Restrictions (Admin kann Limits pro User setzen)
+- 🔲 App-Settings (globale Konfiguration durch Admin)
+- 🔲 Erweiterte Admin-User-Verwaltung (Activity-Log, Stats, Access-Historie)
+
+**E-Mail Templates (v9c):**
+- 🔲 Registrierung + E-Mail-Verifizierung
+- 🔲 Einladungslink
+- 🔲 Passwort-Reset (bereits vorhanden)
+
+**Spätere Features (v9d/v9e):**
+- 🔲 Bonus-System (Login-Streaks → Punkte → Geschenk-Coupons)
+- 🔲 Trial-Reminder-E-Mails (3 Tage vor Ablauf)
+- 🔲 Monatliches Nutzungs-Summary per E-Mail
+- 🔲 Self-Service Upgrade (Stripe-Integration)
+- 🔲 Partner-Verwaltung (Wellpass, Hansefit, etc.)
+- 🔲 Admin-Benachrichtigungen (neue Registrierungen, etc.)
 
 ### Was in v9d kommt:
+- 🔲 Bonus-System & Gamification (Streaks, Achievements)
+- 🔲 Stripe-Integration (Self-Service Upgrade, Subscriptions)
 - 🔲 OAuth2-Grundgerüst für Fitness-Connectoren
 - 🔲 Strava Connector
 - 🔲 Withings Connector (Waage)
 - 🔲 Garmin Connector
 
+---
+
+## v9c Architektur-Details: Subscription & Coupon System
+
+### Datenbank-Schema (Neue Tabellen)
+
+#### **app_settings** - Globale Konfiguration
+```sql
+key, value, value_type, description, updated_at, updated_by
+
+Beispiele:
+- trial_days: 14
+- trial_behavior: 'downgrade' | 'lock'
+- allow_registration: true/false
+- default_tier_trial: 'premium'
+- gift_coupons_per_month: 3
+```
+
+#### **tiers** - Tier-Konfiguration (Admin-editierbar)
+```sql
+id, slug, name, description, sort_order
+max_weight_entries, max_ai_calls_month, max_photos (NULL = unbegrenzt)
+allow_export, allow_activity_import, allow_nutrition_import
+allow_fitness_connectors, allow_gift_coupons
+
+Initial Tiers:
+- free:       30 Einträge, 0 KI, 5 Fotos, kein Export/Import
+- basic:      unbegrenzt, 10 KI/Monat, 50 Fotos, Export/Import
+- premium:    unbegrenzt, unbegrenzt KI, unbegrenzt Fotos, alle Features
+- selfhosted: unbegrenzt alles (für Lars)
+```
+
+#### **coupons** - Coupon-Verwaltung
+```sql
+code, type ('single_use' | 'multi_use_period' | 'gift')
+valid_from, valid_until, grants_tier, duration_days
+max_redemptions, current_redemptions
+created_by, created_for, notes, active
+
+Beispiel Single-Use:
+  Code: FRIEND-GIFT-XYZ, 30 Tage Premium, max 1x
+
+Beispiel Multi-Use Period:
+  Code: WELLPASS-2026-03, gültig 01.03-31.03, unbegrenzte Einlösungen
+```
+
+#### **coupon_redemptions** - Einlösungs-Historie
+```sql
+coupon_id, profile_id, redeemed_at, access_grant_id
+UNIQUE(coupon_id, profile_id) - User kann denselben Coupon nur 1x einlösen
+```
+
+#### **access_grants** - Zeitlich begrenzte Zugriffe
+```sql
+profile_id, granted_tier, valid_from, valid_until
+source ('coupon' | 'admin_grant' | 'trial')
+active (false wenn pausiert durch Wellpass-Override)
+paused_at, paused_by (access_grant_id das pausiert hat)
+
+Stacking-Logik:
+- Multi-Use Period Coupon (Wellpass): pausiert andere grants
+- Single-Use Coupon: stackt zeitlich (Resume nach Ablauf)
+```
+
+#### **user_activity_log** - Aktivitäts-Tracking
+```sql
+profile_id, activity_type, details (JSONB), ip_address, user_agent, created
+
+Activity Types:
+- login, password_change, email_change, coupon_redeemed
+- tier_change, export, ai_analysis, registration
+```
+
+#### **user_stats** - Aggregierte Statistiken
+```sql
+profile_id, first_login, last_login, total_logins
+current_streak_days, longest_streak_days, last_streak_date
+total_weight_entries, total_ai_analyses, total_exports
+bonus_points (später), gift_coupons_available (später)
+```
+
+#### **user_restrictions** - Individuelle Einschränkungen
+```sql
+profile_id, max_ai_calls_month, max_weight_entries, max_photos
+block_export, block_ai, block_import
+reason, set_by (admin_id)
+
+Überschreibt Tier-Limits für spezifische User
+```
+
+#### **profiles** - Erweiterte Spalten
+```sql
+tier, tier_locked (Admin kann Tier festnageln)
+trial_ends_at, email_verified, email_verify_token
+invited_by, contract_type, contract_valid_until
+stripe_customer_id (vorbereitet für v9d)
+```
+
+---
+
+### Backend-Erweiterungen
+
+#### Neue Router (v9c):
+```
+routers/tiers.py         - Tier-Verwaltung (List, Edit, Create)
+routers/coupons.py       - Coupon-System (Redeem, Admin CRUD)
+routers/access_grants.py - Zugriffs-Verwaltung (Current, Grant, Revoke)
+routers/user_admin.py    - Erweiterte User-Verwaltung (Activity, Stats, Restrictions)
+routers/settings.py      - App-Einstellungen (Admin)
+routers/registration.py  - Registrierung + E-Mail-Verifizierung
+```
+
+#### Neue Middleware:
+```python
+require_tier(min_tier)              - Feature-Gate basierend auf Tier
+check_feature_limit(feature, action) - Limit-Prüfung (z.B. max_weight_entries)
+log_activity(type, details)         - Activity-Logging
+```
+
+#### Hintergrund-Tasks (Cron):
+```python
+check_expired_access()    # Täglich 00:00 - Trial/Coupon-Ablauf prüfen
+reset_monthly_limits()    # 1. jeden Monats - AI-Calls zurücksetzen
+update_user_streaks()     # Täglich 23:59 - Login-Streaks aktualisieren
+```
+
+---
+
+### Zugriffs-Hierarchie
+
+```
+Effektiver Tier wird ermittelt durch (Priorität absteigend):
+1. Admin-Override (tier_locked=true) → nutzt profiles.tier
+2. Aktiver access_grant (nicht pausiert, valid_until > now)
+3. Trial (trial_ends_at > now)
+4. Base tier (profiles.tier)
+
+Wellpass-Override-Logik:
+- User hat Single-Use Coupon (20 Tage verbleibend)
+- User löst Wellpass-Coupon ein (gültig bis 31.03)
+- Single-Use access_grant wird pausiert (active=false, paused_by=wellpass_grant_id)
+- Nach Wellpass-Ablauf: Single-Use wird reaktiviert (noch 20 Tage)
+```
+
+---
+
+### Tier-Limits & Feature-Gates
+
+**Daten-Sichtbarkeit bei Downgrade:**
+- Frontend: Buttons/Features ausblenden (Export, KI, Import)
+- Backend: API limitiert Rückgabe (z.B. nur letzte 30 Gewichtseinträge bei free)
+- Daten bleiben erhalten, werden nur versteckt
+- Bei Upgrade wieder sichtbar
+
+**Feature-Checks:**
+```python
+# Beispiel: Gewicht-Eintrag erstellen
+@check_feature_limit('weight', 'create')
+def create_weight_entry():
+    # Prüft: Hat User max_weight_entries erreicht?
+    # Falls ja: HTTPException 403 "Limit erreicht - Upgrade erforderlich"
+```
+
+---
+
+### Frontend-Erweiterungen
+
+#### Neue Seiten:
+```
+RegisterPage.jsx         - Registrierung (Name, E-Mail, Passwort)
+VerifyEmailPage.jsx      - E-Mail-Verifizierung (Token aus URL)
+RedeemCouponPage.jsx     - Coupon-Eingabe (oder Modal)
+AdminCouponsPage.jsx     - Coupon-Verwaltung (Admin)
+AdminTiersPage.jsx       - Tier-Konfiguration (Admin)
+AdminSettingsPage.jsx    - App-Einstellungen (Admin)
+```
+
+#### Neue Komponenten:
+```jsx
+<TierBadge tier="premium" />           // Tier-Anzeige mit Icon
+<FeatureGate tier="basic">...</>       // Feature nur für Basic+ zeigen
+<AccessStatus />                       // "Trial endet in 5 Tagen" Banner
+<CouponInput onRedeem={...} />         // Coupon-Eingabefeld
+<ActivityTimeline activities={...} />  // User-Activity-Log
+<StreakCounter days={7} />             // Login-Streak Anzeige (später)
+```
+
+#### Erweiterte Admin-Seiten:
+```
+AdminUsersPage.jsx erweitert um:
+- Activity-Log Button → zeigt user_activity_log
+- Stats Button → zeigt user_stats
+- Access-Grants Button → zeigt aktive/abgelaufene Zugriffe
+- Restrictions Button → individuelle Limits setzen
+- Grant Access Button → manuell Tier-Zugriff gewähren
+```
+
+---
+
+### E-Mail Templates (v9c)
+
+**1. Registrierung + E-Mail-Verifizierung:**
+```
+Betreff: Willkommen bei Mitai Jinkendo - E-Mail bestätigen
+
+Hallo {name},
+
+vielen Dank für deine Registrierung bei Mitai Jinkendo!
+
+Bitte bestätige deine E-Mail-Adresse:
+{app_url}/verify-email?token={token}
+
+Nach der Bestätigung startet dein 14-Tage Premium Trial automatisch.
+
+Viel Erfolg bei deinem Training!
+Dein Mitai Jinkendo Team
+```
+
+**2. Einladungslink (Admin):**
+```
+Betreff: Du wurdest zu Mitai Jinkendo eingeladen
+
+Hallo,
+
+{admin_name} hat dich zu Mitai Jinkendo eingeladen!
+
+Registriere dich jetzt:
+{app_url}/register?invite={token}
+
+Du erhältst {tier} Zugriff.
+
+Dein Mitai Jinkendo Team
+```
+
+---
+
+### Migrations-Reihenfolge (v9c)
+
+```
+Phase 1 - DB Schema:
+1. app_settings Tabelle + Initialdaten
+2. tiers Tabelle + 4 Standard-Tiers
+3. coupons Tabelle
+4. coupon_redemptions Tabelle
+5. access_grants Tabelle
+6. user_activity_log Tabelle
+7. user_stats Tabelle
+8. user_restrictions Tabelle
+9. profiles Spalten erweitern
+10. Bestehende Profile migrieren (Lars → tier='selfhosted', email_verified=true)
+
+Phase 2 - Backend:
+11. Tier-System Router + Middleware
+12. Registrierungs-Flow
+13. Coupon-System
+14. Access-Grant-Logik
+15. Activity-Logging
+16. Erweiterte Admin-Endpoints
+
+Phase 3 - Frontend:
+17. Registrierungs-Seiten
+18. Tier-System UI-Komponenten
+19. Coupon-Eingabe
+20. Erweiterte Admin-Panels
+21. Feature-Gates in bestehende Seiten einbauen
+
+Phase 4 - Cron-Jobs:
+22. Expired-Access-Checker
+23. Monthly-Reset
+24. Streak-Updater
+
+Phase 5 - Testing & Deployment:
+25. Dev-Testing
+26. Prod-Deployment
+```
+
+---
+
 ## Deployment
 
 ### Infrastruktur