feat(phase-8): billing engine + invoice PDF + mark-paid + overdue escalation

Backend:
- app/services/invoice_pdf.py: Jinja2+WeasyPrint PDF generation, saves to
  /app/data/invoices/{id}.pdf, updates Invoice.pdf_path
- app/templates/invoice.html: professional branded A4 invoice template with
  school details, line items table, totals, payment instructions, paid receipt
- routers/billing.py: GET /invoices/{id}/pdf (auto-generate on demand, FileResponse),
  POST /invoices/{id}/mark-paid (payment_method + reference → status=paid),
  POST /trigger-generate-invoices (manual trigger), school_name in invoice list
- tasks/billing.py: fix missing func import in generate_monthly_invoices,
  new billing.generate_invoice_pdf Celery task, auto-send email after
  invoice creation, check_overdue upgraded with 7-day warning emails and
  30-day school suspension + suspension email

Frontend:
- BillingPage.vue: full rewrite — status filter tabs, school names (not UUIDs),
  PDF download button, mail icon, Mark Paid modal with method/reference fields,
  overdue rows highlighted, pagination, Generate Invoices trigger button
- api.ts: markInvoicePaid, downloadInvoicePdf, triggerGenerateInvoices

.paul/ROADMAP.md

@@ -19,8 +19,8 @@ SMS flow: On-prem TapTrack polls Hub every 30s → Hub queues SMS jobs → Hub s
 ## Current Milestone
 
 **v1.0 — Foundation & Core Services**
-Status: Phase 7 complete — Phase 8 next
-Phases: 7 of 15 complete
+Status: Phase 8 complete — Phase 9 next
+Phases: 8 of 15 complete
 
 ---
 
@@ -35,7 +35,7 @@ Phases: 7 of 15 complete
 | 5     | On-Prem SMS Polling Agent      | 1   | ✅ Complete  | 2026-03-16 |
 | 6     | Super Admin Dashboard UI       | 1   | ✅ Complete  | 2026-03-16 |
 | 7     | School Admin Portal UI         | 1   | ✅ Complete  | 2026-03-16 |
-| 8     | Billing Engine + Invoice PDF   | TBD | Not started  | —          |
+| 8     | Billing Engine + Invoice PDF   | 1   | ✅ Complete  | 2026-03-16 |
 | 9     | Email Dispatcher               | TBD | Not started  | —          |
 | 10    | Support Ticket System          | TBD | Not started  | —          |
 | 11    | Monthly Report Generation      | TBD | Not started  | —          |

.paul/STATE.md

@@ -3,16 +3,16 @@
 ## Current Position
 
 Milestone: v1.0 — Foundation & Core Services
-Phase: 7 of 15 (School Admin Portal UI — complete)
-Plan: Phase 7 complete — Phase 8 next
-Status: **Phase 7 applied — ready to begin Phase 8**
-Last activity: 2026-03-16 — Phase 7 complete (portal pages: suspension banner, credit meter, license countdown, SMS chart, delivery stats, top-up request form, ticket filter/pagination, school details)
+Phase: 8 of 15 (Billing Engine + Invoice PDF — complete)
+Plan: Phase 8 complete — Phase 9 next
+Status: **Phase 8 applied — ready to begin Phase 9**
+Last activity: 2026-03-16 — Phase 8 complete (invoice PDF via Jinja2+WeasyPrint, mark-paid modal, overdue escalation with 7d warning + 30d suspension, bug fix in billing task)
 
 ## Loop Position
 
 ```
 PLAN ──▶ APPLY ──▶ UNIFY
-  ·        ·        ·     [No active plan — Phase 8 planning next]
+  ·        ·        ·     [No active plan — Phase 9 planning next]
 ```
 
 ## Progress
@@ -26,7 +26,7 @@ PLAN ──▶ APPLY ──▶ UNIFY
 - Phase 5  (On-Prem SMS Polling Agent):      [██████████] 100% ✓
 - Phase 6  (Super Admin Dashboard UI):       [██████████] 100% ✓
 - Phase 7  (School Admin Portal UI):         [██████████] 100% ✓
-- Phase 8  (Billing Engine + Invoice PDF):   [░░░░░░░░░░]   0%
+- Phase 8  (Billing Engine + Invoice PDF):   [██████████] 100% ✓
 - Phase 9  (Email Dispatcher):               [░░░░░░░░░░]   0%
 - Phase 10 (Support Ticket System):          [░░░░░░░░░░]   0%
 - Phase 11 (Monthly Report Generation):      [░░░░░░░░░░]   0%
@@ -37,8 +37,8 @@ PLAN ──▶ APPLY ──▶ UNIFY
 
 ## Next Action
 
-Run: `/paul:plan` for Phase 8 — Billing Engine + Invoice PDF
-Resume file: .paul/ROADMAP.md → Phase 8
+Run: `/paul:plan` for Phase 9 — Email Dispatcher
+Resume file: .paul/ROADMAP.md → Phase 9
 
 ## Repo
 

.paul/phases/08-billing-engine/README.md

@@ -0,0 +1,46 @@
+# Phase 08: Billing Engine + Invoice PDF
+
+**Status:** Complete
+**Completed:** 2026-03-16
+
+## Goal
+
+Automated monthly invoice generation, PDF export, mark-as-paid workflow, and overdue escalation.
+
+## What was built
+
+### Backend
+
+**`billing/invoice_pdf.py`** (new service)
+- `generate_invoice_pdf(invoice_id)` — renders Jinja2 HTML template → WeasyPrint PDF
+- Stores at `/app/data/invoices/{invoice_id}.pdf`
+- Sets `Invoice.pdf_path` in DB
+
+**`templates/invoice.html`** (new Jinja2 template)
+- Branded HTML invoice with school name, billing period, line items table, totals, payment instructions
+
+**`routers/billing.py`** additions
+- `GET /billing/invoices/{id}/pdf` — serve PDF (FileResponse), auto-generate if not yet created
+- `POST /billing/invoices/{id}/mark-paid` — set paid_at, payment_method, payment_reference → status=paid
+- Invoice list now includes `school_name` (joined)
+
+**`tasks/billing.py`** fixes + additions
+- Fixed missing `func` import in `generate_monthly_invoices`
+- `check_overdue` enhanced:
+  - 7-day overdue → send warning email to school billing contact
+  - 30-day overdue → suspend school (set status = suspended)
+- `generate_monthly_invoices` auto-queues `send_invoice_email_task` after creating each invoice
+
+### Frontend
+
+**`BillingPage.vue`** — full rewrite
+- Invoice table with school name (not raw UUID), status badges, PDF download button
+- Mark-as-paid modal: payment method dropdown + reference field
+- Status filter + pagination
+- "Generate Invoices" quick action (triggers Celery task)
+- Overdue invoices highlighted in red
+
+**`api.ts`** additions
+- `downloadInvoicePdf(id)` — opens PDF in new tab
+- `markInvoicePaid(id, data)` — PATCH to mark-paid endpoint
+- `triggerGenerateInvoices()` — POST to trigger monthly invoice generation