Hi Ran,
I do agree with you, that the flag documentation is - at least occassionally - a little sparse. And not always easy to find among the many documents and webpages. However, it seems to me that your main issue is first to understand how the bit-based quality flags work at all.
Each quality flag, corresponding to an integer pixel value (like your 134217728 and 2283798528 examples) is actually a package of multiple bit-value flags (in the Product Data Format Specification (PDFS) the bit-value flags are also named “words”). Your example quality flags contain at least 32 bits (or words). Each bit can take on the value of 0 or 1, and the flag value is calculated as the sum of the bit value times the bit number over all bit numbers.
to illustrate that for your example values (I leave out bit# 0-20 as they are 0 for both example pixels):
bit 21: 0 0 - 1 2097152
bit 22: 0 0 - 0 0
bit 23: 0 0 - 0 0
bit 24: 0 0 - 0 0
bit 25: 0 0 - 0 0
bit 26: 0 0 - 0 0
bit 27: 1 134217728 - 1 134217728
bit 28: 0 0 - 0 0
bit 29: 0 0 - 0 0
bit 30: 0 0 - 0 0
bit 31: 0 0 - 1 2147483648
sum : 134217728 - 2283798528
where first column shows the bit number, second (forth) the bit value of the first (second) example pixel, third (fifth) the resulting pixel value contribution from this bit for the first (second) example. Last row shows the sum of the individial bit contributions, ie the resulting pixel value.
That is, beside the common (cloud?) flag at bit27, the second example pixel has additional flags set at bit21 and bit31.
I have no idea, what meaning the individual bits correspond to in your data, but a short description of the word meanings should be found (a) in the PDFS corresponding to your data (a number of PDFS is available from the Sentinel Documents Library - select the one you need depending e.g. on the level - L1/L2 - of your data), but also (b) in the attribute information of the quality flag entry in your data (in a field called ‘flag_meanings’).
I also have no idea, whether SNAP/s3tbx contains a tool to easily do this bit de-wrapping. I use numpy’s view and unpackbits functions for that.
I hope this helps a bit…
Best wishes,
jm