feat: implement hybrid address system and premium search logic

- Added centralized, self-learning GeoService (ZIP, City, Street)
- Implemented Hybrid Address Management (Centralized table + Denormalized fields)
- Fixed Gamification logic (PointsLedger field names & filtering)
- Added address autocomplete and two-tier (Free/Premium) search API
- Synchronized UserStats and PointsLedger schemas

docs/V01_gemini/10_Billing_Credits_Subscriptions.md

@@ -73,4 +73,41 @@ Ha az előfizetés lejár, a rendszer az alábbi fokozatos korlátozásokat veze
 
 1.  **Grace Period (30 nap):** Csak adatrögzítés lehetséges, a statisztikai modulok és exportok zárolva vannak.
 2.  **Zárolás (60 nap):** A fiók írásvédetté válik (Read-only). Nincs új adatrögzítés.
-3.  **Helyreállítás:** 6 hónapon belüli visszamenőleges befizetés esetén minden korábbi adat és funkció azonnal újraaktiválódik.
+3.  **Helyreállítás:** 6 hónapon belüli visszamenőleges befizetés esetén minden korábbi adat és funkció azonnal újraaktiválódik.
+
+## 4. Economic Model & Exchange Rates
+
+### 4.1 Dinamikus Árfolyamok (Admin Config)
+A rendszer támogatja a többvalutás elszámolást. Az átváltási arányok a `system_configs` táblából jönnek.
+* **Példa konfiguráció:**
+    * 1 HUF = 50 Kredit
+    * 1 EUR = 20.000 Kredit (változtatható)
+    * 1 USD = 18.500 Kredit
+
+### 4.2 Referral Commission (Admin Config)
+A jutalékrendszer paraméterezhető, alapértelmezett értékei:
+* **Level 1 (Közvetlen):** 10%
+* **Level 2:** 5%
+* **Level 3:** 2%
+* *Megjegyzés:* Adminisztrátori joggal ezek bármikor módosíthatók, visszamenőleges hatály nélkül.
+
+### 4.3 Kifizetés (Payout)
+* **Threshold:** A kifizetés igénylésének alsó határa alapértelmezetten **1.000.000 Kredit**.
+* Ez az érték adminisztrátori döntéssel csökkenthető/növelhető a rendszer érettségétől függően.
+
+
+## 5. Marketplace & Vanity Items
+
+### 5.1 Árazási Logika
+A rendszer támogatja a dinamikus árazást a kozmetikai elemeknél is.
+* **Fix áras termékek:** Egyszerű levonás a `coin_balance`-ból vagy `credit_balance`-ból.
+* **Időszakos ajánlatok:** A katalógusban beállítható `sale_price` és `sale_end_date`.
+
+### 5.2 Vásárlási Folyamat
+1.  **Check:** Van-e elég fedezet (Wallet)?
+2.  **Deduct:** Tranzakció rögzítése a `wallet_transactions` táblában (`type='purchase_item'`).
+3.  **Grant:** Tétel beírása a `user_inventory` táblába.
+4.  **Equip:** Opcionálisan azonnali beállítás (pl. profilkép keret).
+
+### 5.3 Bővíthetőség
+Új elem hozzáadásához **nem kell kódot módosítani**, csak a `shop_catalog` JSON-t kell frissíteni az Admin felületen. A kliens alkalmazás (App/Web) dinamikusan tölti be a kínálatot ebből a JSON-ből.