MAGIK-925: Multi-Currency Support — Display, Storage & Conversion

[MAGIKBIT]

Story 4 — Multi-Currency Support

Epic: EPIC-010 — Global Internationalization & Multi-Language Support (GitHub #100)
Priority: P1

User Story

As a MagikTap user in a non-USD market, I want prices displayed in my local currency with proper formatting, so I can understand costs without mental conversion.

Requirements

Supported Currencies (Initial)

Currency	Code	Symbol	Decimal	Grouping
US Dollar	USD	$	. (dot)	, (comma)
Euro	EUR	€	, (comma)	. (dot)
Ethiopian Birr	ETB	Br	.	,
Eritrean Nakfa	ERN	Nfk	.	,
Mexican Peso	MXN	$	.	,
Saudi Riyal	SAR	﷼	.	,
UAE Dirham	AED	د.إ	.	,
British Pound	GBP	£	.	,

Database Changes

• Add currency column (CHAR(3), ISO 4217) to name_info table — user preferred currency
• Add currency_rates table: id, base_currency, target_currency, rate, updated_at
• Store all prices internally in USD (or base currency), convert for display
• Admin can set manual exchange rates (v1 — no live feeds)

Currency Service

• CurrencyService::format(float $amount, string $currencyCode, string $locale): string
• CurrencyService::convert(float $amount, string $from, string $to): float
• CurrencyService::getSymbol(string $currencyCode): string
• CurrencyService::getSupportedCurrencies(): array
• Uses PHP NumberFormatter (intl extension) for locale-aware formatting

View Integration

• All price displays use format_currency() helper (Story Add ssh container #1)
• Plan pricing on subscription pages
• Payment amounts on transaction boards
• Commission amounts on commission boards
• Invoice/receipt generation

Acceptance Criteria

#	Criteria	Priority
1	Prices display with correct symbol and formatting per locale	P0
2	Currency preference stored per user in name_info	P0
3	Admin can set exchange rates manually	P1
4	All finance boards display in user currency	P1
5	Plan pricing shows localized amounts	P1
6	Internal storage remains in base currency	P1
7	NumberFormatter handles all 5 locale formats	P1
8	Currency selector in profile settings	P2

Files to Create

• app/app.portalv2/app/Libraries/CurrencyService.php
• app/app.portalv2/app/Models/CurrencyRateModel.php
• sql/migration_add_currency_support.sql

Files to Modify

• app/app.portalv2/app/Views/admin/finance/plans.php — localized pricing
• app/app.portalv2/app/Views/admin/finance/transactions.php — localized amounts
• app/app.portalv2/app/Views/admin/finance/commissions.php — localized amounts
• app/app.portalv2/app/Views/profile/settings.php — currency preference selector