docs: update subscription feature documentation - M7 (refs #55)

backend/src/features/subscriptions/CLAUDE.md

@@ -0,0 +1,55 @@
+# backend/src/features/subscriptions/
+
+Stripe payment integration for subscription tiers and donations.
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature overview with architecture diagram | Understanding subscription flow |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP controllers and routes | API endpoint changes |
+| `domain/` | Services and type definitions | Business logic changes |
+| `data/` | Repository for database operations | Database queries |
+| `external/stripe/` | Stripe API client wrapper | Stripe integration |
+| `migrations/` | Database schema | Schema changes |
+| `jobs/` | Scheduled background jobs | Grace period processing |
+
+## Key Patterns
+
+- Repository mapRow() converts snake_case to camelCase
+- Webhook idempotency via stripe_event_id unique constraint
+- Tier sync to user_profiles.subscription_tier on changes
+- Grace period: 30 days after payment failure
+- Vehicle selections for tier downgrades (not deleted, just gated)
+
+## API Endpoints
+
+### Subscriptions (Authenticated)
+- GET /api/subscriptions - Current subscription
+- POST /api/subscriptions/checkout - Create subscription
+- POST /api/subscriptions/cancel - Schedule cancellation
+- POST /api/subscriptions/reactivate - Cancel pending cancellation
+- POST /api/subscriptions/downgrade - Downgrade with vehicle selection
+- PUT /api/subscriptions/payment-method - Update payment
+- GET /api/subscriptions/invoices - Billing history
+
+### Donations (Authenticated)
+- POST /api/donations - Create payment intent
+- GET /api/donations - Donation history
+
+### Webhooks (Public)
+- POST /api/webhooks/stripe - Stripe webhook (signature verified)
+
+## Environment Variables
+
+- STRIPE_SECRET_KEY
+- STRIPE_WEBHOOK_SECRET
+- STRIPE_PRO_MONTHLY_PRICE_ID
+- STRIPE_PRO_YEARLY_PRICE_ID
+- STRIPE_ENTERPRISE_MONTHLY_PRICE_ID
+- STRIPE_ENTERPRISE_YEARLY_PRICE_ID