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/05_AUTH_AND_IDENTITY_SPEC.md

@@ -91,4 +91,19 @@ Minden regisztrációnál automatikusan létrejön:
 ---
 
 ## 7. Adattárolási Stratégia (Technikai)
-- A rugalmas okmányadatokat (`identity_docs`) és a vészhelyzeti kapcsolatokat (`ice_contact`) **JSONB** mezőkben tároljuk a `persons` táblában a kereshetőség és a jövőbeli bővíthetőség érdekében.
+- A rugalmas okmányadatokat (`identity_docs`) és a vészhelyzeti kapcsolatokat (`ice_contact`) **JSONB** mezőkben tároljuk a `persons` táblában a kereshetőség és a jövőbeli bővíthetőség érdekében.
+
+## 4. Multi-Account & Identity Linking
+A felhasználók több e-mail címet is csatolhatnak egyetlen profilhoz, hogy könnyen válthassanak a magánszemély és a céges flotta-menedzser szerepkörök között.
+
+### 4.1 Szabályrendszer
+* **Limit:** Egy felhasználói profilhoz maximum **3** másodlagos e-mail cím csatolható.
+* **Elsődleges cím:** Ez a belépési azonosító és a hivatalos értesítési cím.
+* **Context Switching:** A felhasználó a fejlécben válthat a "Személyes" és a "Céges" nézetek között (pl. Flotta Manager mód).
+
+### 4.2 Account Linking Folyamat
+1. User belép az elsődleges fiókba.
+2. `Settings -> Linked Accounts -> Add New`.
+3. Rendszer küld egy megerősítő linket az új címre.
+4. Ha a linkre kattint, az új cím hozzáadódik a `user_identities` táblához.
+5. Ha az új címen már volt regisztráció: A rendszer felajánlja az **Account Merge** (Fiókegyesítés) lehetőségét (biztonsági kérdések után).

docs/V01_gemini/06_Database_Guide.md

@@ -109,4 +109,78 @@ Minden üzleti változó az Admin UI-ról állítható:
 
 ## 4.3 Crowdsourced Szervezetek
 - **Lifecycle:** draft_user -> draft_bot -> community_verified -> official.
-- **Gamification:** XP/Kredit jóváírás csak sikeres Bot vagy Owner validáció után.
+- **Gamification:** XP/Kredit jóváírás csak sikeres Bot vagy Owner validáció után.
+
+## 6. Service & Organization Extensions (V2)
+
+### 6.1 `data.system_configs` (Dinamikus Beállítások)
+Kódba égetett értékek helyett adatbázisból vezérelt működés.
+* `key` (VARCHAR): Pl. `referral_bonus_L1`, `exchange_rate_EUR`, `payout_threshold`.
+* `value` (JSONB): Pl. `{"amount": 10, "unit": "percent"}`, `{"rate": 400.0}`.
+* `is_active` (BOOLEAN).
+
+### 6.2 `data.service_reviews` (Okos Értékelés)
+* `user_id`, `organization_id`.
+* `rating` (1-5).
+* `proof_url` (Számla/Munkalap fotó URL).
+* `is_active` (BOOLEAN): Csak az aktív számít bele az átlagba (lásd Gamification logika).
+
+### 6.3 `data.wallet_transactions`
+* `original_currency`: (HUF, EUR, USD).
+* `exchange_rate`: Az adott pillanatban érvényes váltószám.
+
+## 7. Referrals & Invitations
+* `data.referrals`: Hierarchikus fa szerkezet (`inviter_id`, `invitee_id`, `level`).
+* `data.invitations`:
+    * `code`: Random string (pl. `X7K9P2`).
+    * `type`: 'private' (72h) vagy 'company' (168h).
+    * `target_role`: A meghívott jogosultsága (Driver, Manager).
+
+## 8. Virtual Goods & Inventory (Digitális Javak)
+
+### 8.1 `data.user_inventory`
+Ez a tábla tárolja a felhasználó által megszerzett vagy vásárolt kozmetikai elemeket (NEM jogosultságok, hanem vagyontárgyak).
+
+* `id` (UUID): Egyedi azonosító.
+* `user_id` (FK): A tulajdonos.
+* `item_id` (VARCHAR): A katalógusban lévő azonosító (pl. `avatar_frame_neon`).
+* `metadata` (JSONB): Opcionális egyedi tulajdonságok (pl. sorszámozott NFT-szerű elemknél: `{"serial": 42}`).
+* `acquired_at` (TIMESTAMP): Mikor szerezte.
+* `is_equipped` (BOOLEAN): Éppen használja-e (pl. ez az aktív avatar kerete).
+
+### 8.2 Shop Catalog Configuration (`system_configs`)
+A `key = 'shop_catalog'` alatt tároljuk a bolt kínálatát JSON formátumban.
+
+**Példa JSON struktúra:**
+```json
+{
+  "categories": ["avatars", "badges", "profile_themes"],
+  "items": {
+    "badge_early_adopter": {
+      "name": "Korai Felfedező",
+      "price": 0,
+      "currency": "free",
+      "condition": "reg_date < '2025-01-01'",
+      "image_url": "/assets/badges/early.png"
+    },
+    "frame_gold_mechanic": {
+      "name": "Arany Szerelő Keret",
+      "price": 5000,
+      "currency": "credit",
+      "rarity": "legendary",
+      "effect": "shine_animation",
+      "image_url": "/assets/frames/gold.png"
+    }
+  }
+}
+
+## 5. Geo-Location and Address Master Data
+A rendszer normalizált címkezelést alkalmaz az adatminőség biztosítása érdekében.
+
+### 5.1 Geo Adattáblák
+- `data.geo_postal_codes`: ZIP és Település kapcsolata (Unique: country + zip + city).
+- `data.geo_streets`: Utcanevek listája, ZIP azonosítóhoz kötve.
+- `data.geo_street_types`: Közterület típusok szótára (út, utca, tér...).
+
+### 5.2 GIS Adatok
+Minden telephely koordinátája `GEOGRAPHY(POINT, 4326)` típusként van tárolva, amely lehetővé teszi a PostGIS alapú távolságmérést.

docs/V01_gemini/07_REGISTRATION_INVITATION_AND_API.md

@@ -98,4 +98,19 @@ A biztonsági paraméterek környezeti változókon keresztül szabályozhatók:
 -   `POST /api/v1/auth/complete-kyc`: KYC adatok beküldése és aktiválás.
 -   `POST /api/v1/auth/invite/send`: Meghívó generálása.
 -   `GET /api/v1/auth/invite/verify/{token}`: Token validálása.
--   `POST /api/v1/auth/recover-identity`: Szigorú (KYC alapú) helyreállítás.
+-   `POST /api/v1/auth/recover-identity`: Szigorú (KYC alapú) helyreállítás.
+
+## 5. Invitation Logic Specifications
+
+### 5.1 Meghívó Kódok
+* **Formátum:** Véletlenszerű alfanumerikus string (pl. `A8B2X9`). NEM tartalmazhat személyes adatot.
+* **Generálás:** Minden "Meghívás" gombnyomásra új, egyedi token generálódik.
+
+### 5.2 Lejárati Idők (TTL)
+A meghívók érvényessége a típustól függ:
+* **Magánszemély (C2C):** 72 óra (3 nap). Sürgető érzést kelt.
+* **Céges / Flotta (B2B):** 168 óra (1 hét). Figyelembe veszi a lassabb céges ügymenetet.
+
+### 5.3 Biztonság
+* A meghívó link tartalmaz egy aláírt JWT tokent, amely rögzíti a `target_org_id`-t (melyik flottába hívjuk) és a `role`-t (pl. sofőr).
+* A kód felhasználása után a link érvénytelenné válik (One-time use).

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.

docs/V01_gemini/11_Gamification_Social.md

@@ -8,4 +8,77 @@
 
 ## 2. Véleményezés (Review)
 - **Szabály:** Csak "Verified Visit" után lehet értékelni (GPS vagy Számla).
-- **Fellebbezés:** A szerviz jelezheti, ha a vélemény valótlan. Ilyenkor a Moderátorok (vagy magas szintű Validátorok) döntenek.
+- **Fellebbezés:** A szerviz jelezheti, ha a vélemény valótlan. Ilyenkor a Moderátorok (vagy magas szintű Validátorok) döntenek.
+
+## 3. "Service Hunt" (Szerviz Vadászat)
+A felhasználók játékosított formában validálják az adatbázist.
+
+### 3.1 Validációs Szabályok
+* **Radius:** A felhasználónak **50-100 méteren** belül kell tartózkodnia a szerviz GPS koordinátáihoz képest a validáláshoz.
+* **Jutalom:** Csak akkor jár, ha a validáció sikeres (GPS + Fotó).
+* **Bot vs. Ember:**
+    * Ha a Bot találta a szervizt, de nincs validálva: A felhasználó megkapja a "Validator" bónuszt.
+    * Ha már validálva van (Status: Verified): A felhasználó látja a térképen, hogy "Már validálva", nem jár érte pont (kivéve adatfrissítés).
+
+### 3.2 Okos Értékelési Rendszer (Review Logic)
+A rendszer védi a szolgáltatókat a "Review Bombing"-tól, de jutalmazza a konzisztenciát.
+
+* **Negatív élmény (1-3 csillag):**
+    * Egy felhasználótól **csak a legutolsó** negatív értékelés számít bele az átlagba.
+    * Ha a user újra értékel (mert visszament), az előző negatív értékelés `is_active = False` státuszba kerül (de az admin látja az előzményeket).
+* **Pozitív élmény (4-5 csillag):**
+    * Minden pozitív értékelés számít és összeadódik (kumulatív).
+    * Ez ösztönzi a szervizt a folyamatos jó teljesítményre.
+
+    ## 4. Social Flexing & Vanity Items
+A "dicsekvési faktor" kezelése.
+
+### 4.1 Megjelenítési Helyek
+* **Profil oldalon:** A megszerzett jelvények (Badges) "vitrinje".
+* **Ranglistákon:** Kiemelt név, egyedi háttérszín vagy ikon a név mellett.
+* **Térképen:** Egyedi pin ikon a saját járműveknél (pl. arany színű autó ikon a térképen a sima kék helyett).
+
+### 4.2 Ritkasági Szintek (Rarity)
+A tárgyakhoz ritkasági szintet rendelünk a `system_configs`-ban:
+1.  **Common (Gyakori):** Bárki megveheti olcsón.
+2.  **Rare (Ritka):** Drágább, vagy teljesítményhez kötött (pl. 10 validált szerviz).
+3.  **Epic (Epikus):** Csak Prémium+ tagoknak vagy nagyon sok kreditbe kerül.
+4.  **Legendary (Legendás):** Egyedi eventeken szerezhető (pl. "Service Hunt 2026 Győztes").
+
+### 4.3 "Equipped" Status
+A felhasználónak lehet 50 jelvénye, de egyszerre (típustól függően) csak korlátozott számút mutathat meg (pl. 3 Slot a profilkép alatt). Ezt a `user_inventory.is_equipped` flag kezeli.
+
+## 5. Büntetőpontok és Rehabilitáció (Strike System)
+
+A rendszer 3-szintes büntetőrendszert alkalmaz a hibás vagy szándékosan téves adatok kiszűrésére.
+
+### 5.1 Büntetőpontok (Strikes)
+* **Ok:** Szándékos félrevezetés, nem létező szerviz rögzítése, hamis fotók.
+* **Következmény:** 3 strike után a felhasználó véglegesen vagy ideiglenesen ki lesz tiltva a "Service Hunt" és validációs feladatokból.
+
+### 5.2 Rehabilitációs Logika (Strike eltávolítás)
+Egy büntetőpont (1 strike) levonható az alábbi feltételek teljesülése esetén (Adminról állítható értékek):
+* **Javítás:** 10 sikeres és elfogadott adatjavítás (más hibájának korrigálása).
+* **Validáció:** 20 sikeres és megerősített validáció.
+* **Példás rögzítés:** 3 olyan új szerviz rögzítése, amit a Bot és az Admin is 100%-ban validnak talál.
+
+### 5.3 Területi Monitoring (Geofence Blacklist)
+Amennyiben egy adott földrajzi körzetből (pl. egy városrész) kiugróan sok (százalékos arányban mérve) téves adat érkezik, a rendszer automatikusan korlátozhatja az onnan érkező új regisztrálók hozzáférését a szociális feladatokhoz, amíg az Admin felül nem vizsgálja a helyzetet.
+
+## 6. Versenyrendszer (Leaderboards)
+
+A közösségi munka (Service Hunt, Validáció) egy globális és régiós ranglistát táplál.
+
+### 6.1 Ranglista kategóriák
+* **The Explorer (A Felfedező):** Legtöbb új szerviz rögzítése.
+* **The Verifier (A Hitelesítő):** Legtöbb sikeres adat-visszaigazolás.
+* **The Master Mechanic:** Legtöbb technikai adat kiegészítés.
+
+### 6.2 Szintlépési Bónuszok (Milestones)
+A fejlődés nem csak dicsőség, hanem gazdasági előny is.
+* **Level 5:** 1.000 Kredit jutalom.
+* **Level 10:** 5.000 Kredit + "Expert" jelvény.
+* **Level 20:** Egyedi avatar keret + állandó 5% kedvezmény a hirdetési árakból (céges esetén).
+
+### 6.3 Éves/Havi Szezonok
+Minden hónap végén az első 3 helyezett extra Kreditet vagy "Voucher"-t kap, amit a partnereinknél (szervizeknél) válthat be.

docs/V01_gemini/12_Operations_Backup_Monitoring.md

@@ -9,4 +9,10 @@
 ## Monitoring
 - **Dozzle:** Valós idejű log nézegető (Port 8888).
 - **Healthcheck:** Docker `healthcheck` minden konténeren.
-- **Alerts:** Email értesítés, ha az API 5xx hibát dob.
+- **Alerts:** Email értesítés, ha az API 5xx hibát dob.
+
+## 4. Anti-Fraud & Device Logging
+
+A visszaélések elkerülése érdekében a rendszer rögzíti a beküldéshez használt eszközök adatait.
+* **Device Fingerprinting:** Egyedi azonosító rögzítése (`device_id`).
+* **Metadata Validation:** Képek feltöltésekor kötelező az EXIF GPS adatok ellenőrzése. Amennyiben az EXIF adatok hiányoznak vagy eltérnek a rögzített helyszíntől (>250m), a bejegyzés automatikusan "Manual Review" státuszba kerül.

docs/V01_gemini/18_ASSET_AND_FLEET_SPECIFICATION.md

@@ -127,4 +127,50 @@ A rendszer háromlépcsős tárolási és feldolgozási logikát alkalmaz az opt
 
 3. **Vault (NAS - Hosszú távú tároló):**
    - A feldolgozott, nagyfelbontású (max 1600px) WebP állomány átkerül a NAS-ra: `/mnt/nas/app_data/organizations/{id}/vault/`.
-   - A NAS-hoz csak akkor fordul a rendszer, ha a felhasználó kifejezetten a dokumentum nagy változatát kéri.
+   - A NAS-hoz csak akkor fordul a rendszer, ha a felhasználó kifejezetten a dokumentum nagy változatát kéri.
+
+   ## 5. Discovery Bot Strategy
+
+### 5.1 Prioritási Sorrend
+A Botok az alábbi sorrendben pásztázzák az adatforrásokat:
+1.  **Land (Földi járművek):**
+    * Személyautók (Car), Motorok (Bike), Teherautók (Truck).
+    * Adatforrás: Márkakereskedői listák, Gyártói API-k.
+2.  **Infrastructure (Infrastruktúra):**
+    * Benzinkutak, Elektromos töltők (OpenChargeMap API).
+    * Ezek könnyen elérhető, statikus adatok.
+3.  **Services (Szervizek):**
+    * Google Maps API, Cégjegyzék adatok.
+    * Ezeket jelöli meg a rendszer "Unverified" (Bot-talált) státusszal.
+
+### 5.2 Adatgazdagítás
+A Bot nem csak a nevet keresi. Célzottan gyűjti:
+* Nyitvatartási idők.
+* Kapcsolattartói adatok (Email, Weboldal).
+* Közösségi média linkek.
+* *Szabály:* A Bot által hozott adat felülírható a "Service Hunt" során a felhasználó által (magasabb megbízhatóság).
+
+## 6. Multi-Source Consensus Logic
+A szervizek és szolgáltatók hitelességét nem csak az Admin, hanem a források száma határozza meg.
+
+### 6.1 Bizalmi szintek (Confidence Score)
+* **Score 1:** Egyetlen forrás (Bot vagy User). Státusz: `pending`.
+* **Score 2:** Két független forrás megerősítése.
+* **Score 3+:** Automatikus hitelesítés (`verified`). Nincs szükség emberi beavatkozásra.
+
+### 6.2 Bot Adatforrások (Priority: Car & Bike)
+A Botok az alábbi sorrendben dolgoznak:
+1. Hivatalos gyártói oldalak (Márkaszervizek).
+2. Szakmai adatbázisok (pl. Autóklub, Kamarák).
+3. Google/Social media API-k.
+
+## 4. Telephelyek (Locations) és Szervizpontok
+Minden szolgáltató (Organization) több telephelyet tarthat fenn.
+
+### 4.1 Kötelező Adatstruktúra
+Minden telephely rögzítésekor az alábbi bontott címadatok kötelezőek:
+- Irányítószám, Város, Közterület neve, Közterület típusa, Házszám.
+- Opcionális: Helyrajzi szám (parcel_id) külterületi vagy HRSZ alapú azonosításhoz.
+
+### 4.2 Validációs Folyamat
+A rögzített címek automatikusan bekerülnek a Master Geo adatbázisba, építve a rendszer globális címjegyzékét.

docs/V01_gemini/19_ADMIN_AND_PERMISSIONS_SPEC.md

@@ -74,4 +74,16 @@ A cégek hitelesítése három szinten történik:
 ## 7. B2B Jutalék és MLM Korlátok
 - **Direct Referral:** Szervezet által meghívott másik szervezet esetén kizárólag az **1. szintű (L1)** jutalék jár.
 - **MLM Kivétel:** A szervezetek nem építhetnek többszintű hálózatot; a kifizetés minden esetben fix üzleti megállapodás vagy egyedi szerződés alapján történik.
-- **Adminisztrátori Meghívók:** Csak manuálisan generálhatók, és szigorúan **24 órás** lejárati idővel rendelkeznek.
+- **Adminisztrátori Meghívók:** Csak manuálisan generálhatók, és szigorúan **24 órás** lejárati idővel rendelkeznek.
+
+## 6. Dinamikus Szabálymotor (Rule Engine)
+A rendszer minden fontos paramétere a `data.system_settings` táblában tárolt JSON objektumokból származik.
+
+### 6.1 Módosítási protokoll
+* Az Admin felületen módosított értékek (pl. Kredit jutalom összege) azonnal érvénybe lépnek.
+* A módosítás után a Backend Cache-t (`ConfigService`) üríteni kell.
+
+### 6.2 Paraméterezhető modulok
+* **Service Hunt:** Távolságok, XP/Kredit szorzók.
+* **Fraud Protection:** Strike limitek, kitiltási idők.
+* **Billing:** EUR/HUF/USD váltószámok, csomagárak, jármű-slot árak.