Title: Licentia Mpumalanga (LMPU) – Income Workflow, Payment Allocation Logic, VAT / Application Fees / Royalty Rules (Program Specification)

Gentlemen and Ladies 

Please implement the Financial Income workflow for the Licentia Mpumalanga system as per the specifications below. This must support a two-layer model (Franchisee document creation + Provincial Head Office financial control), with strict allocation rules and accurate reporting for accountants and management.

  _____  

1) Core Principle (Two-Layer Bookkeeping)

1.1 Franchisee System (Document Creation + Visibility Only)

*	Franchisee creates Quotation → Invoice.
*	Franchisee cannot allocate payments, cannot move funds, cannot change VAT/royalty logic.
*	Franchisee system is for:

*	Invoice status visibility (Outstanding / Part Paid / Paid)
*	Income breakdown visibility
*	Monthly franchisee payout view (information only)

1.2 Provincial System (Financial Master)

*	All client payments are received into Licentia Mpumalanga bank accounts.
*	Provincial Head Office allocates receipts to invoice numbers and controls:

*	VAT reservation and VAT payment cycle (every 2 months)
*	Application fee holding and staged payments to government departments
*	Royalty calculation (cash-based; only on full settlement)
*	Monthly franchisee payout calculation (cash-based)

Provincial system is the source of truth; Franchisee system mirrors the payment and breakdown once allocation is completed.

  _____  

2) Document Numbering Rules (Mpumalanga)

2.1 Invoice Numbers

All Mpumalanga invoices must be sequential with prefix:

*	LMPU-000001, LMPU-000002, … continuing forward.

2.2 Quotation Reference Carry-Over

*	The Quotation Number must carry over onto the Invoice record.
*	Reason: bank payment references often contain the quote number and/or invoice number and must be searchable for allocation.

  _____  

3) Invoice Structure (As Per UI Screenshot)

Invoices consist of only the following financial components:

3.1 Earnings (Vatable)

1.	Professional Fee (service rendered)
2.	Miscellaneous Fee (additional work outside scope)

VAT is calculated ONLY on Earnings.

3.2 Expenses (Non-VAT / Pass-Through)

3.	Application Fees (government/municipality fees for the specific application)

*	No VAT is charged on Application Fees
*	These fees are held by the Province and paid to the relevant government entities when required by application stage.

3.3 Totals Panel (Must Auto-Calculate)

*	Subtotal (Earnings Total)
*	VAT (on Earnings only)
*	Grand Total (Earnings + VAT + Application Fees)
*	Franchise Royalty (calculated ONLY when fully paid; see rules below)
*	“Your Profit” / Franchisee Share (70% of Earnings; only finalised when fully paid)

  _____  

4) Payment Allocation (Provincial Head Office Only)

4.1 Receiving Payment

When funds reflect in the Licentia Mpumalanga bank account, Provincial staff will:

*	Capture a Receipt / Payment Received
*	Allocate it to an invoice using:

*	Invoice Number (LMPU-xxxxxx) and/or
*	Quotation Number and/or
*	Bank reference search

4.2 Invoice Status Logic

*	Outstanding: paid total = 0
*	Part Paid: 0 < paid total < invoice grand total
*	Paid: paid total = invoice grand total

  _____  

5) Critical Rule: Partial Payment Allocation Priority

If an invoice is Part Paid, the received amount must be allocated in this strict order:

1.	VAT
2.	Application Fees
3.	Earnings (Professional Fee + Miscellaneous Fee)

This must be hard-coded. No alternative allocation order is permitted.

Royalty is not calculated during partial payments.

  _____  

6) Royalty Rules (Mpumalanga)

6.1 Royalty Base

Royalty applies ONLY to Earnings, i.e.:

*	Professional Fee + Miscellaneous Fee

Royalty does NOT apply to:

*	VAT
*	Application Fees

6.2 Timing of Royalty Calculation

Royalty must be calculated:

*	✅ Only when payment is received
*	✅ Only when the invoice becomes fully paid
*	❌ Not at invoice creation
*	❌ Not proportionally for part payments

6.3 Royalty Rate and Split

When invoice is fully paid:

*	Royalty = 30% ? (Professional + Miscellaneous)
*	Franchisee portion = 70% ? (Professional + Miscellaneous)

  _____  

7) Bank Accounts & “Allocation Instructions” Output

Provincial system must support and track balances for:

1.	Business Operating Account
2.	VAT Savings Account
3.	Application Fees Account

When a payment is allocated, the system must generate a clear “Allocation Instruction Summary” for Provincial personnel indicating:

*	Amount to reserve/transfer to VAT Savings Account (VAT portion)
*	Amount to reserve/transfer to Application Fees Account (Application fees portion)
*	Remaining earnings portion (Business Account)
*	On full settlement only:

*	Royalty amount (30% of earnings) recognised as Provincial profit
*	Franchisee payable amount (70% of earnings) recognised as Franchisee payable

Even if bank transfers are done manually, the system must track internal transfers/allocations so balances remain accurate in-system.

  _____  

8) Application Fees – Department-Level Breakdown (Required)

Application Fees must be stored and reportable per government entity/department (examples):

*	Liquor Authority
*	Municipality (trade licence / zoning / etc.)
*	Fire Department
*	Petroleum (where applicable)
*	SAMRO / SAMPRA (where applicable)

This is required so Head Office can see:

*	what is being held,
*	for which department,
*	for which application,
*	and when it must be paid as the application progresses.

  _____  

9) Franchisee Notifications & Display (Sync Back)

Once Provincial Head Office allocates a receipt:

9.1 Franchisee System Must Auto-Update

*	Invoice status updates (Outstanding/Part Paid/Paid)
*	Payment allocation visibility
*	Morning Welcome notification: “Payment received – proceed with application”

9.2 Franchisee Dashboard Breakdown (Paid Invoice)

For a paid invoice, show:

*	Professional Fee (total)
*	Miscellaneous Fee (total)
*	VAT (deducted in full – Province pays SARS)
*	Application Fees (held by Province – paid to government; no VAT)
*	Royalty deducted (30% of Earnings; only on full settlement)
*	Net Franchisee Position (70% of Earnings; payable monthly)

For Part Paid:

*	show amounts allocated so far (VAT → Application Fees → Earnings)
*	Royalty remains “Not applicable until fully paid”.

  _____  

10) Provincial Reporting Requirements (Must Have)

10.1 Per Franchisee (Monthly / YTD)

*	Total invoices issued
*	Total cash collected
*	VAT reserved / payable
*	Application fees held by department
*	Total earnings collected
*	Royalty earned by province (30% on fully paid invoices only)
*	Franchisee payable (70% on fully paid invoices only)

10.2 Provincial Summary (All Mpumalanga Franchisees)

*	Monthly and yearly Provincial Profit from royalty
*	Total VAT reserved/payable (bi-monthly VAT cycle support)
*	Total application fees held (by department + by application)
*	Total franchisee payables outstanding

  _____  

11) Permissions (Mandatory)

*	Franchisee role:

*	create quotations/invoices
*	view statuses/breakdowns
*	cannot allocate payments

*	Provincial Head Office role:

*	capture receipts
*	allocate payments
*	generate allocation instructions
*	manage VAT/application fee holdings
*	view all franchisees and provincial summaries

  _____  

Please implement the above exactly, as it is the required operational model for Licentia Mpumalanga and must remain consistent for audit, VAT compliance, and franchise payout integrity.