docs: fix phase READMEs and STATE.md — add full scope/plan to phases 9-15, fix stale last-commit field

.paul/phases/11-monthly-reports/README.md

@@ -1,9 +1,64 @@
-# Phase 11: Monthly Report Generation
+# Phase 11: Monthly Report Generation + Email
 
 **Status:** Not started
+**Depends on:** Phase 9 (Email), Phase 12 (On-Prem Data Pull)
 
 ## Goal
-Auto monthly report email to schools with attendance summary and SMS usage.
 
-## Plans
-- [ ] TBD — run /paul:plan when Phase 10 is complete
+On the 1st of each month, automatically generate and email a comprehensive report to each
+active school summarising their SMS usage, credit consumption, and invoice for the period.
+Super admin can manually trigger reports. School portal shows report history.
+
+## Planned Scope
+
+### Backend
+
+**Enhance `reports.send_monthly_reports` Celery task** (currently a stub)
+- For each active school:
+  1. Fetch SMS stats for prior month (sent, failed, delivery rate, credit burn)
+  2. Fetch attendance data from `school_monthly_stats` (populated by Phase 12)
+  3. Fetch invoice for the period (if exists)
+  4. Render `monthly_report.html` Jinja2 template
+  5. Send email to `school.billing_email`
+  6. Store report record in `monthly_reports` table
+
+**`monthly_reports` table** (new model)
+- `id`, `school_id`, `report_month` (YYYY-MM), `email_sent_at`, `report_data` (JSON),
+  `created_at`
+
+**Manual trigger endpoint**
+- `POST /api/reports/send/{school_id}` — super admin triggers report for a specific school
+
+**School portal: report history**
+- `GET /api/portal/reports` — school admin lists their past reports
+- `GET /api/portal/reports/{id}` — view report detail (JSON data rendered as HTML)
+
+**`monthly_report.html`** Jinja2 email template
+- School name + period header
+- SMS stats: sent, failed, delivery rate, credit burn
+- Attendance summary (if available from Phase 12, else "data unavailable")
+- Invoice summary for the period
+- Credit balance as of report date
+
+### Frontend
+
+**PortalReportsPage.vue** (new portal page)
+- List of past monthly reports (month, email sent date, SMS count, status)
+- Click to view report detail
+
+**Super admin** — manual report trigger button in SchoolDetailPage
+
+**Router + sidebar** — add /portal/reports route and nav item
+
+## Key Files to Create/Modify
+
+- `backend/app/models/report.py` (new — monthly_reports table)
+- `backend/app/tasks/reports.py` — enhance from stub
+- `backend/app/routers/reports.py` (new)
+- `backend/app/templates/email/monthly_report.html` (new)
+- `backend/app/main.py` — include reports router
+- `backend/migrations/versions/003_monthly_reports.py` (new)
+- `frontend/src/pages/portal/PortalReportsPage.vue` (new)
+- `frontend/src/router/index.ts` — add /portal/reports
+- `frontend/src/components/sidebar/PortalSidebar.vue` — add Reports nav item
+- `frontend/src/lib/api.ts` — portal report functions